home *** CD-ROM | disk | FTP | other *** search
/ Gigarom 1 / Gigarom Macintosh Archives (Quantum Leap)(CDRM1080320)(1993).iso / FILES / HYP / H-I / HyperHackers.cpt / Hyper-Hackers Queue 1.0 / card_28813.txt < prev    next >
Text File  |  1989-02-26  |  3KB  |  72 lines
  1. -- card: 28813 from stack: in.0
  2. -- bmap block id: 0
  3. -- flags: 0000
  4. -- background id: 3797
  5. -- name: 
  6.  
  7.  
  8. -- part contents for background part 1
  9. ----- text -----
  10.  
  11. From: mitch@well.UUCP (Mitchell Waite)
  12.  
  13. Date: 5 Mar 88 06:56:25 GMT
  14.  
  15. >>It [manual for software] is done last and fast.
  16. >
  17. I don't think you understand the process of documentation from the inside at
  18. all.  In all the companies I've worked, the docs never came "fast and last".
  19. The documentation team at Microsoft, for example, is included in product
  20. development from the start. 
  21. >
  22.  
  23. Sure, what do I know about documentation? But you're a lucky guy Mr. Arrants.
  24. You have not had to dirty your hands with companies that ignore documentation.
  25. But come off your tower, Microsoft is not the way it is everywhere. 
  26.  
  27. Sure,  over the last few years they have paid a great deal of attention to
  28. documentation. I am just finishing writing a book on programming with Microsoft
  29. Quick C for Microsoft Press, and have written several others for Microsoft
  30. Press. I have had an opportunity to work with beta Quick C, watch the manuals go
  31. through there revisions, and yes I am impressed. But that is just not the way it
  32. in the vast majority of computer and software companies. Don't misread me. I
  33. admire the improvements Microsoft has made in documentation, and it would be
  34. nice if other companies followed their lead. I'm just saying that is not the way
  35. it is in the vast majority of companies.
  36.  
  37. >
  38. Nope.  What leaves these holes [in the documentation from software companies]
  39. are:
  40. 1.  Changes to the software that can't make it into the documentation
  41. because the books are either finishing the run at the printer or that
  42. the books are in the warehouse waiting for the software to arrive for
  43. shipping.
  44. 2.  Cost of Goods.  If a product sells to a distributor for, say $200,
  45. COG can be 15% - $25.  That's $25 for the package, disks, disk labels,
  46. keyboard templates, collateral materials, registration card, and
  47. documentation.  Let's say that the documentation itself is 10% ($20)
  48. COG.  I don't think that software companies are doing too poor a job.
  49. The manuals MUST be comprehensive.  Third party books rarely are.
  50. >
  51.  
  52. I won't say I think you know nothing about publishing, but the holes you mention
  53. are mostly minor. The main ones are caused by the fact that manufacturers don't
  54. take responsibility to teach people how to use their products. Instead they say
  55. "Oh, you must already know how to program in C. We just tell you the "right"
  56. syntax, the limitations, and if you are lucky we'll give you an example too".
  57. The manuals cop out by only giving syntax and leaving the tutorials to other
  58. folks. Why? I think its because most manufacturers are the poorest users of
  59. their own products! Sorry, but I see it over and over. Its the ivory tower
  60. syndrome. Lets see what other people think.
  61.  
  62. Yes, manuals, especially ones on complex products like languages and operating
  63. systems, have to be comprehensive. So what are we suppose to think: don't expect
  64. to learn anything from them? Certainly Microsoft offers more manual pounds per
  65. dollar than any other company. But if these manuals where such a panacea, I
  66. would not be writing this book.
  67.  
  68.  
  69.  
  70. -- part contents for background part 45
  71. ----- text -----
  72. Re: HyperTalk Books, How to Judge?